---
sidebar_label: Naming conventions
sidebar_position: 9.5
description: Customizing auto generated names in Hasura with a naming convention
keywords:
  - hasura
  - docs
  - schema
  - API
  - naming
  - naming convention
  - conventions
---

import Tabs from '@theme/Tabs';
import Thumbnail from '@site/src/components/Thumbnail';
import TabItem from '@theme/TabItem';
import GraphiQLIDE from '@site/src/components/GraphiQLIDE';

# Postgres: Naming Conventions

## Introduction

The Hasura GraphQL Engine generates names for various schema objects (fields, types, arguments, etc.) and the naming
convention for these autogenerated names can be customized to suit your needs.

:::tip Note

Naming conventions are an experimental feature and can be enabled by adding `naming_convention` to the
`HASURA_GRAPHQL_EXPERIMENTAL_FEATURES` environment variable array or with the server flag `--experimental-feature`.

:::

:::note Supported from

Naming conventions are available at version `v2.8.0` and higher.

:::

:::info Database Support

Naming conventions are only available on Postgres sources.

:::

## Supported naming conventions

Currently, Hasura provides two naming conventions:

- `hasura-default`: This is the **default** naming convention used in the Hasura server and is used when a naming
  convention is not explicitly specified. In this naming convention, all names will use snake casing (`snake_case`) and
  defined enum table values will not change.

- `graphql-default`: This is a new naming convention which is more popular in the Javascript ecosystem. Suppose you have
  a table called `my_table` in schema `my_schema`, this convention will work as follows:
  - Type names will be [pascal-cased](https://en.wiktionary.org/wiki/Pascal_case). In the above example, Hasura Server
    will generate the type `MySchemaMyTable` for the select field.
  - Field names will be [camel-cased](https://en.wiktionary.org/wiki/CamelCase). In the above example, Hasura Server
    will generate the field name `mySchemaMyTableAggregate` for the aggregate field.
  - Argument names and boolean operators will be camel-cased. For example, Hasura Server will generate argument names
    like `orderBy`, `distinctOn`.
  - Enum values will be upper-cased. i.e. for an enum table, all the values will be upper-cased when used as enum value
    in Hasura Server.

| Naming Convention | Field names | Type names  | Arguments  | Enum values |
| ----------------- | ----------- | ----------- | ---------- | ----------- |
| `hasura-default`  | Snake case  | Snake case  | Snake case | as defined  |
| `graphql-default` | Camel case  | Pascal case | Camel case | Uppercased  |

:::tip Note

- Setting [custom table and field names](/schema/postgres/custom-field-names.mdx) in Hasura will override the naming
  convention of the source. For example, if the custom table name is set to `my_table` and `naming_convention` is
  `graphql-default`, the field names generated will be `my_table`, `my_tableByPk`, `my_tableAggregate` and so on.
- `hasura-default` is the naming convention used prior to `v2.8.0`.

:::

**For example:**

Consider a schema named, `app_db`, with the following structure:

1. **app_users**: A table with the columns **user_id**, **username**, **last_seen**, **favorite_day** and
   **referred_by**.
2. **week_days**: An enum table with column **day_names** and rows **monday**, **tuesday** and so on.
3. We have a foreign key set up between `week_days.day_names` and `app_users.favorite_day`.

For the above schema, a sample GraphQL query will look like the following with the different naming conventions:

**hasura-default**

<GraphiQLIDE
  query={`query get_user_aggregate {
  app_db_app_users_aggregate(
    distinct_on: referred_by,
    where: {favorite_day: {_eq: sunday}}
  ) {
    aggregate {
      count
      stddev_pop {
        user_id
      }
    }
  }
}
  `}
  response={`{
  "data": {
    "app_db_app_users_aggregate": {
      "aggregate": {
        "count": 0,
        "stddev_pop": {
          "user_id": null
        }
      }
    }
  }
}
  `}
/>

**graphql-default**

<GraphiQLIDE
  query={`query get_user_aggregate {
  appDbAppUsersAggregate(
    distinctOn: referredBy,
    where: {favoriteDay: {_eq: SUNDAY}}
  ) {
    aggregate {
      count
      stddevPop {
        userId
      }
    }
  }
}
`}
  response={`{
  "data": {
    "appDbAppUsersAggregate": {
      "aggregate": {
        "count": 0,
        "stddevPop": {
          "userId": null
        }
      }
    }
  }
}
`}
/>

:::tip Behavior of custom table name

For the `graphql-default` naming convention and a [custom table name](/api-reference/syntax-defs.mdx#table-config) for a
given table/view, the following rules are followed:

- The custom table name will not be modified (change of case) if it is the first entity for a given name.
- The custom table name may be modified if the name is being prefixed by something.

| Sl. no. | Custom table name | Select    | Select by pk  | Typename | Insert table one   |
| ------- | ----------------- | --------- | ------------- | -------- | ------------------ |
| 1       | table_one         | table_one | table_oneByPk | tableOne | insertTable_oneOne |
| 2       | tableOne          | tableOne  | tableOneByPk  | tableOne | insertTableOneOne  |
| 3       | TableOne          | TableOne  | TableOneByPk  | TableOne | insertTableOneOne  |

:::

## Set default naming convention for all sources {#pg-default-naming-convention}

For setting the default naming convention for all sources, set the environment variable
`HASURA_GRAPHQL_DEFAULT_NAMING_CONVENTION` to one of `hasura-default` or `graphql-default`.

This means any database source will follow this naming convention unless explicitly set to something else.

## Set naming convention for a particular source {#pg-source-naming-convention}

<Tabs groupId="user-preference" className="api-tabs">
  <TabItem value="console" label="Console">

Currently setting the database naming convention is only allowed at the time of connecting your database.

Head to the `Data -> Manage -> Connect Database` page. Under the `GraphQL Field Customization` section after, enabling
the naming conventions, you can choose the naming convention of your choice.

<Thumbnail src="/img/schema/naming-convention.png" alt="Naming Convention" />

  </TabItem>
  <TabItem value="cli" label="CLI">

Head to the `/metadata/databases/databases.yaml` file and add the database configuration as below:

```yaml {6-7}
- name: <db_name>
  configuration:
    connection_info:
      database_url:
        from_env: <DB_URL_ENV_VAR>
  customization:
    naming_convention: hasura-default
  tables: []
  functions: []
```

Apply the metadata by running:

```bash
hasura metadata apply
```

  </TabItem>
  <TabItem value="api" label="API">

You can set the naming convention of a particular source using the `customization` field in the
[pg_add_source](/api-reference/metadata-api/source.mdx#metadata-pg-add-source) metadata API.

```http {16-18}
POST /v1/metadata HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin

{
  "type": "pg_add_source",
  "args": {
    "name": "<db_name>",
    "configuration": {
      "connection_info": {
        "database_url": {
          "from_env": "<DB_URL_ENV_VAR>"
        }
      }
    },
    "customization": {
      "naming_convention": "hasura-default"
    },
    "replace_configuration": true
  }
}
```

  </TabItem>
</Tabs>

:::tip Note

Setting the convention in the source customization will override the default naming convention.

:::
